home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.083 < prev    next >
Encoding:
Text File  |  1991-11-15  |  10.9 KB  |  252 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #83:         Resource Manager Stuff
  9.  
  10. Revised by:  Dave "No Middle Name" Lyons                        December 1991
  11. Written by:  Dave Lyons                                              May 1990
  12.  
  13. This Technical Note answers your miscellaneous Resource Manager questions.
  14.  
  15. Changes since March 1991:  Added a warning about UniqueResourceID in 
  16. System 5.0.4 and earlier.
  17. _____________________________________________________________________________
  18.  
  19.  
  20.  
  21. UniqueResourceID
  22.  
  23. In System Software 5.0.4 and earlier, calling UniqueResourceID with an 
  24. IDRange value of $FFFF does not work reliably.  It sometimes returns a 
  25. system-range ID ($07FFxxxx) if there are already system-range resources 
  26. of the specified type present in the current search path.
  27.  
  28. If you are using a development utility that generates resource IDs using 
  29. UniqueResourceID, check the results to make sure no system-range 
  30. resource IDs are being used by accident.
  31.  
  32. What SetCurResourceFile Does
  33.  
  34. SetCurResourceFile is documented in Chapter 45 of the Apple IIgs Toolbox 
  35. Reference, Volume 3 (see especially "Resource File Search Sequence" near the 
  36. beginning of the chapter).
  37.  
  38. This explanation might make you think SetCurResourceFile rearranges the 
  39. search path, but it does not; instead, it just makes searches start at a 
  40. different place in the path.  SetCurResourceFile is useful for controlling 
  41. what resource files are searched, not for changing the search order.
  42.  
  43.  
  44. How the Toolbox Uses Resources as Templates
  45.  
  46. The toolbox uses several types of resources as templates for creating other 
  47. objects.  Examples include rControlList, rControlTemplate, and rWindParam1. 
  48. The toolbox automatically releases these resources from memory as soon as 
  49. itis through with them, so there is no need to create your template resources 
  50. with special purge levels in an effort to free more memory.  It is not a 
  51. problem.
  52.  
  53.  
  54. Using Resources From Window Update Routines
  55.  
  56. In System Software 5.0.4 and earlier there is no special code to set the 
  57. current resource application when the system calls an application window 
  58. update routine (See Apple IIgs Technical Note #71 for notes on NDAs and the 
  59. current resource application).
  60.  
  61. To avoid a situation where a window update routine cannot get needed 
  62. resources, obey the following rules:
  63.  
  64. 1.  Application window update routines must either (a) assume that the 
  65. resource application has the same value it had when the window was created, 
  66. or (b) save, set, and restore the current resource application, using 
  67. GetCurResourceApp and SetCurResourceApp.
  68.  
  69. 2.  NDAs that start the Resource Manager must not call application window 
  70. update routines, and they must not cause application window update routines 
  71. to be called (for example, if an NDA calls TaskMaster to handle a modal 
  72. dialog or movable modal dialog, the tmUpdate bit in wmTaskMask must be off).
  73.  
  74. CurResourceApp in InfoDefProcs and Custom Windows
  75.  
  76. The current resource application has no guaranteed value when an information 
  77. bar definition procedure or custom window definition procedure gets control. 
  78. These must always save, set, and restore the current resource application 
  79. using GetCurResourceApp and SetCurResourceApp.
  80.  
  81.  
  82. StartUpTools Opens Resource Forks Read-Only
  83.  
  84. When StartUpTools opens your application's resource fork, it opens it with 
  85. read-only access.  If your application needs to make changes to the resources 
  86. on disk, you need to close the fork and reopen it with read and write access. 
  87. To close it, use GetCurResourceFile and CloseResourceFile; to reopen it, use 
  88. LGetPathname2 and OpenResourceFile.
  89.  
  90. Note:   You must update the resFileID field in the StartStop record if you
  91.         close and reopen your resource fork.  CloseResourceFile disposes the 
  92.         handles of any resources in memory from the file you're closing, so   
  93.         you must call DetachResource on any resources you need to keep.  (If 
  94.         you pass an rToolSTartup resource to StartUpTools, the system
  95.         detaches it for you automatically.)
  96.  
  97.  
  98. Calling StartUpTools From a Shell Application (File Type $B5, EXE)
  99.  
  100. StartUpTools tries to open the current application's resource fork.  It 
  101. determines the pathname of the "current application" by examining prefix 
  102. 9:and making a GET_NAME GS/OS call, but do not assume it will always 
  103. construct the pathname this way.  If you call StartUpTools from a shell 
  104. application and expect it to open your EXE file's resource fork, you will be 
  105. disappointed.
  106.  
  107. If GS/OS has launched your application, life is good usually, though, a shell 
  108. has loaded your shell application directly, so GET_NAME returns the name 
  109. ofthe shell instead of the name of your application file.
  110.  
  111. To open your shell file's resource fork, call ResourceStartUp, get the 
  112. pathname by calling LGetPathname2 on your user ID, and pass the pathname to 
  113. OpenResourceFile.
  114.  
  115. What's NIL in a Resource Map?
  116.  
  117. The resource maps for open resource files are kept in memory, and the 
  118. structure is defined in chapter 45 of Apple IIgs Toolbox Reference, Volume 3.
  119.  
  120. The resHandle field of a resource reference record (ResRefRec) is defined as 
  121. "Handle of resource in memory.  A NIL value indicates that the resource has 
  122. not been loaded into memory."  In this case, NIL means that the middle two 
  123. bytes of the four-byte field are zero.  In other words, a NIL entry in the 
  124. resource map may have a non-zero value in the low-order byte.
  125.  
  126.  
  127. LoadResource and SetResLoad(FALSE)
  128.  
  129. When you call LoadResource on a locked or fixed resource and SetResLoad isset 
  130. to FALSE, you may get Memory Manager error $0204 (lockErr), because the 
  131. Resource Manager tries to allocate a locked or fixed zero-length handle,which 
  132. the Memory Manager does not permit.
  133.  
  134.  
  135. Adjusting the Search Depth
  136.  
  137. If you wish to add some resource files to the beginning of a resource search 
  138. path and adjust the depth so that the end point of the search is unchanged, 
  139. it's tempting to use SetResourceFileDepth(0) to get the current depth, add 
  140. one, and set this new depth with SetResourceFileDepth.
  141.  
  142. The problem is that the search depth is often -1 ($FFFF), meaning "search 
  143. until the end of the chain."  If you add your adjustment to -1, you do not 
  144. usually get the intended effect.  A solution is just to check for $FFFF and 
  145. not adjust the depth in that case.
  146.  
  147.  
  148. CurResourceApp after ResourceShutDown
  149.  
  150. After a ResourceShutDown call, the current resource application is always 
  151. $401E.  (The Resource Manager starts itself up at boot time with its own 
  152. memory ID, $401E.  Do not ever call ResourceShutDown while the current 
  153. resource application is $401E.)
  154.  
  155.  
  156. Restoring the CurResourceApp
  157.  
  158. If you need to start up and shut down the Resource Manager without disturbing 
  159. the current resource application, call GetCurResourceApp before 
  160. ResourceStartUp, and call SetCurResourceApp to restore the old value after 
  161. ResourceShutDown.
  162.  
  163. It does not help to call GetCurResourceApp after ResourceStartUp, since the 
  164. application just started up is always the current resource application.
  165.  
  166. Shell programs which start the Resource Manager need to callSetCurResourceApp 
  167. after regaining control from a subprogram (for example, an EXE file) which 
  168. may have started and shut down the Resource Manager, leaving the current 
  169. resource application set to $401E instead of the shell's ID.
  170.  
  171. Shell programs that do not start the Resource Manager have nothing to worry 
  172. about.  In this case the current resource application is normally $401E, so 
  173. when a subprogram calls ResourceShutDown life is still wonderful.
  174.  
  175.  
  176. What Information is Kept For Each Resource Application?
  177.  
  178. When you switch resource applications with SetCurResourceApp, that takes care 
  179. of all the application-specific information the Resource Manager has.
  180.  
  181. There is no need to separately preserve the current resource file, the search 
  182. depth, the SetResourceLoad setting, or any application resource converters 
  183. that are logged in.  All of this information is already recorded separately 
  184. for each resource application.
  185.  
  186.  
  187. Debugging Information
  188.  
  189. The following information is provided for your convenience during program 
  190. development.  It allows you to check exactly what user IDs are using the 
  191. Resource Manager, what files are in their search paths, and what resource 
  192. converters are logged in.
  193.  
  194. Do not depend on this information in your program; it is subject to change in 
  195. future versions of the Resource Manager.
  196.  
  197. All the Resource Manager's data structures are rooted in the Resource Manager 
  198. tool set's Work Area Pointer (WAP).  To get the Resource Manager's WAP, call 
  199. GetWAP (in the Tool Locator) with userOrSystem = $0000 and tsNum = $001E.
  200.  
  201. The WAP value is a handle to the Resource Manager's block of global data. 
  202. Several interesting areas in this block are listed below.
  203.  
  204. +$0A2   curApp          Word        Offset into the globals block of the
  205.                                     current resource application's 
  206.                                     Application Record.
  207. +$2B0   sysFile         Long        Handle of system file map, or NIL if 
  208.                                     none.
  209. +$2B4   sysConvertList  Long        Handle of system converter list, or NIL 
  210.                                     if none.
  211. +$2B8   appList     (20*n bytes)    List of Application Records (20 bytes 
  212.                                     each).
  213.  
  214. Each Application Record has this format:
  215.  
  216. +000    appFlag         Word    0=entry available, 1=entry used, $FFFF = end 
  217.                                 of array.
  218. +002    appID           Word    User ID of application.
  219. +004    appFiles        Long    Handle of application's first resource map,
  220.                                 NIL=none.
  221. +008    appCur          Long    Handle of application's current resource map,
  222.                                 NIL=none.
  223. +012    appConverters   Long    Handle of application's converter list, 
  224.                                 NIL=none.
  225. +016    appReadFlag     Word    1=read resources, 0=don't read 
  226.                                 (SetResourceLoad).
  227. +018    appFileDepth    Word    Number of files to search in this path.
  228.  
  229. Converter lists have this format:
  230.  
  231. +000    n               Word        Number of entries in the table (entries 
  232.                                     can be unused).
  233. +002    theConverters   6*n bytes   List of converter entries (6 bytes each).
  234.  
  235. Each Converter entry has this format:
  236.  
  237. +000    resType     Word    Resource type for this converter ($0000 for 
  238.                             unused entry).
  239. +002    convAddress Long    Address of resource converter.
  240.  
  241. The format for a resource map is described starting on page 45-17 of Apple 
  242. IIgs Toolbox Reference, Volume 3.
  243.  
  244. Remember, don't depend on this information in your application; use it during
  245. debugging, and use it to write debugging utilities.
  246.  
  247.  
  248. Further Reference
  249. _____________________________________________________________________________
  250.   o  Apple IIgs Toolbox Reference, Volume 3
  251.   o  Apple IIgs Technical Note #71, DA Tips and Techniques
  252.